package bigbrother.command;

import bigbrother.modules.Module;

/**
 * A Command is something that an IRC user can invoke, to have the IRC bot do something. Commands are provided by {@link
 * Module}s.
 * <p/>
 * The Command also includes documentation.
 *
 * @author Hans Haggstrom
 */
public interface Command
{

    //======================================================================
    // Public Methods

    /**
     * @return the command identifier.  If it is an empty string "", the module name in itself is treated as this
     *         command.
     */
    String getCommandName();

    /**
     * @return description of the command and the parameters it takes. Use newlines to split the documentation in
     *         suitable length lines.
     */
    String getDocumentation();

    /**
     * Called when a command is called for a specific module by some user.
     *
     * @param channel    The channel on which the command was sent, or null if it was sent as a private message.
     * @param sender     The nick of the person who sent the command.
     * @param login      The login of the person who sent the command.
     * @param hostname   The hostname of the person who sent the command.
     * @param parameters The parameter string for the command.
     *
     * @return the reply for the channel the command was issued in, or in private chat if the command was sent
     *         privately. If null is returned, no reply is sent.
     */
    String doCommand( final String channel,
                      final String sender,
                      final String login,
                      final String hostname,
                      final String parameters );

}
